Skip to content

Merge upstream emulate main into github-only - #11

Open
byapparov wants to merge 20 commits into
github-onlyfrom
chore/sync-upstream-20261116
Open

byapparov wants to merge 20 commits into
github-onlyfrom
chore/sync-upstream-20261116

Conversation

@byapparov

Copy link
Copy Markdown
Member

Summary

Merges upstream vercel-labs/emulate main (18 commits since the fork point 1566b8e, up to ad7b0de) into github-only.

What upstream brings for GitHub:

Fork-specific resolution:

  • Keeps the GitHub-only package set. Upstream changes to removed packages, apps, examples and skills are dropped.
  • packages/github-emulator emits declarations with tsc and bundles them with rolldown-plugin-dts, as upstream's emulate package does.
  • The GitHub-only edition enables strict_scopes unless a seed opts out, so a token GitHub never issued (for example one issued before reset()) gets 401 Bad credentials, as on GitHub. Upstream's default treats it as the default user, which turned the runtime test's expected 401 into a 404.
  • .github/workflows/ci.yml is unchanged: the pushing token has no workflow scope. Upstream also runs pnpm type-check:tsc; that script exists here and passes, and can be added to CI separately.

Verification

In node:24-bookworm-slim:

  • pnpm install --frozen-lockfile, pnpm build, pnpm type-check, pnpm type-check:tsc, pnpm lint (0 errors), pnpm format:check: pass.
  • pnpm test: core 113/113, github 180/180, github-emulator 6/6.
  • pnpm test:smoke: pass. test:cross-host (Firefox) is left to CI.

aictrl local GitHub e2e stack built from this tree: onboarding 6/6, backlog MCP 20/20. Repository picker 13/15; the two failures reproduce on the current pin 8f2b8b4 and are stale aictrl tests, fixed on the aictrl side.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Br5cbz3i7Y5PaRdx3DUfXx

ctate and others added 19 commits November 5, 2026 11:56
- Lint with oxlint instead of ESLint, typescript-eslint and eslint-config-next, which need the TypeScript 6 API; oxlint reports the same 41 warnings
- Build declaration files with tsc instead of tsup, and bundle emulate's api.d.ts with rolldown-plugin-dts; the published types are unchanged
- Set types to node, which TypeScript 6 stopped including by default, and keep the examples on their own TypeScript and ESLint
- Run `tsup --watch src` in each package's dev script. Plain `--watch` skips files that aren't in the JavaScript build, so edits to type-only files never re-emitted declarations
* Match trailing and inner * in route patterns

compilePath only treated a pattern that was exactly * or /* as a
wildcard, so app.use("/auth/*", mw) or app.get("/files/*", h) compiled to
a literal path and never matched. A trailing /* now matches the prefix and
everything under it, and a * elsewhere matches one path segment.
Patterns without these forms compile to the same regex as before.

* Keep a star literal unless it is a whole path segment

A star inside a segment, as in /files*, was also treated as a wildcard,
so it matched /filesx but not /files. It is now a wildcard only when it
is the whole segment.
* Advertise the listening address in default base URLs

With --host set to a specific address such as a LAN IP, the server bound only to that address but the banner, seeded data and service responses still advertised localhost, which refused connections.

resolveBaseUrl now takes the listening host. Loopback and wildcard hosts keep localhost; any other host is used as the URL host, with IPv6 literals bracketed. An explicit base URL, seed baseUrl and portless still take precedence. The CLI, project mode and createEmulator all pass the host through.

* Document the listening host fallback and pin the createEmulator wiring

The docs still named http://localhost:<port> as the last base URL
fallback. They now describe the listening host. A test starts an
emulator on a network address and checks the URL it reports.
* Detect a busy wildcard port before binding a specific address

On macOS a server bound to 127.0.0.1 starts even when another process
holds the same port on the wildcard address, so emulate came up on a
port it did not own and never reported "Cannot listen".

serve() now probes the wildcard address of the same family before
listening and reports EADDRINUSE through the server error event. Port 0
and wildcard hosts skip the probe. Listening now starts after the probe
resolves, so one legacy-runner test waits for the listen call.

* Detect a busy port by connecting to the address we will serve

The wildcard bind probe gave a false positive on Linux: a program on
another specific address (for example ::1) made the wildcard bind fail,
so an emulator on a free 127.0.0.1 was refused.

serve() now resolves the host that listen will bind and makes one short
connection to it. If something accepts, it reports EADDRINUSE; refused
or timed out means free. The other program sees one short connection.
Port 0 and wildcard hosts skip the check. Adds core tests for a wildcard
holder and for a holder on a different address.

* Check for a busy port before serve, not inside it

serve deferred listen until the check finished, so a caller that used
the address right away raced it, and an invalid port threw inside a
promise nobody awaited, leaving a server that never listened or errored.
serve listens synchronously again. The check is now assertPortFree,
which the startup paths await before they call serve, and an invalid
port is left for listen to report.
* feat(aws): forward S3, SQS, IAM, STS, and KMS to an external backend

Set aws.backend.url to proxy those services to an AWS-compatible endpoint such as AWS Emulator, keeping the emulator's port and path prefixes. Cognito and the inspector stay local. Seeded resources are created through the backend's API once per emulator start.

The AWS SDK e2e suites can also target an external endpoint through AWS_EMULATOR_E2E_URL.

* fix(aws): honor aws.region and rewrite every backend URL in forwarded responses

Seeding and unsigned forwarded requests now sign for aws.region, and buckets outside us-east-1 are created with a location constraint. Queue URLs on the backend's host, ListDeadLetterSourceQueues results, S3 POST <Location> bodies, and redirects keep pointing at the emulator. Compressed SQS responses pass through unchanged.

* fix(aws): do not cache a failed backend seed

A rejected seed stayed in the seeded WeakMap, so a reset reused the rejected promise and every later request failed until restart. Only successful seeds are kept now.

* fix(aws): require an http or https backend URL

`new URL("localhost:4566")` parses with `localhost:` as the protocol, so a scheme-less backend URL passed validation and every request then failed with 502.

* fix(aws): name the failing region key in the backend error

A bad s3.buckets[].region was reported as aws.region, which points at the wrong config key.

* fix(aws): route backend requests by credential scope

The service came only from emulate's path prefixes, so a bucket named kms, sqs, iam, or sts was forwarded to that service. The signed service now takes precedence and the path prefix is stripped only when it matches.

* fix(aws): answer backend failures in each SDK's error protocol

S3, IAM, and STS clients only parse XML errors, so a JSON 502 surfaced as an XML parse error and lost the message. Those services get awsErrorXml-style XML now, while SQS and KMS keep JSON.

* docs(aws): start emulate through npx in the skill

Bare `emulate` in zsh runs the shell builtin, not the CLI.

* test(aws): drop redundant external-target guards

Every describe in the cognito SDK suite is skipIf(externalTarget), so vitest never runs these hooks against an external endpoint.

* fix(aws): retry a failed backend seed on the next request

A rejected seed promise stayed cached on the instance, so forwarded requests kept answering 502 after the backend came up and only a reset recovered. The seed attempt now lives in the per-store state, drops itself when it fails, and the proxy starts a new attempt; a successful seed still survives resets.
Brings the 18 upstream commits since 1566b8e: TypeScript 7 with tsc-ts,
oxlint, declarations emitted by tsc instead of tsup, and the GitHub
changes from upstream vercel-labs#388 (private repositories return 404 to callers
who cannot see them, OAuth codes bound to the requesting client, OAuth
token and grant revocation, opt-in strict_scopes).

Fork-specific resolution:
- Keep the GitHub-only package set; drop upstream changes to removed
  packages, apps, examples and skills.
- packages/github-emulator emits declarations with tsc and bundles them
  with rolldown-plugin-dts, as upstream's emulate package does.
- The GitHub-only edition enables strict_scopes unless a seed opts out,
  so a token GitHub never issued gets 401 Bad credentials, as on GitHub.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Br5cbz3i7Y5PaRdx3DUfXx
Comment thread CHANGELOG.md

<!-- release:start -->

### Improvements

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 Changelog omits 0.13.1 auth behavior changes.

Suggested change
### Improvements
Add 0.13.1 entries for: strict GitHub-style token validation (default-on in the `github-emulator` package; `strict_scopes: false` in the seed opts out), OAuth code↔client binding, the new token/grant revocation endpoints, and private-repo 404 masking; document `strict_scopes` in the README seed-options section next to `GitHubSeedConfig`.
🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, CHANGELOG.md:7-15):

Problem: Changelog omits 0.13.1 auth behavior changes
Detail: The 0.13.1 entry documents only the toolchain upgrade, but this PR also ships user-observable auth behavior changes with no entry anywhere: (1) `createGitHubEmulator` now defaults `strict_scopes` to true, so tokens the emulator never issued get 401 Bad credentials instead of silently acting as the fallback user — a breaking change for existing consumers of the published package; (2) new `DELETE /applications/:client_id/{token,grant}` revocation endpoints; (3) OAuth authorization codes are now bound to the client_id they were issued to; (4) private repositories now answer 404 (not 401/403) to callers who cannot see them (orgs.test.ts expectation changed 403→404). The `strict_scopes` seed option is also absent from the docs. Users upgrading 0.13.0→0.13.1 get silent behavior flips.
Suggested fix: Add 0.13.1 entries for: strict GitHub-style token validation (default-on in the `github-emulator` package; `strict_scopes: false` in the seed opts out), OAuth code↔client binding, the new token/grant revocation endpoints, and private-repo 404 masking; document `strict_scopes` in the README seed-options section next to `GitHubSeedConfig`.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

The 0.13.1 entry documents only the toolchain upgrade, but this PR also ships user-observable auth behavior changes with no entry anywhere: (1) createGitHubEmulator now defaults strict_scopes to true, so tokens the emulator never issued get 401 Bad credentials instead of silently acting as the fallback user — a breaking change for existing consumers of the published package; (2) new DELETE /applications/:client_id/{token,grant} revocation endpoints; (3) OAuth authorization codes are now bound to the client_id they were issued to; (4) private repositories now answer 404 (not 401/403) to callers who cannot see them (orgs.test.ts expectation changed 403→404). The strict_scopes seed option is also absent from the docs. Users upgrading 0.13.0→0.13.1 get silent behavior flips.

### Improvements

- Upgraded the build to **TypeScript 7**, with `tsc` emitting package declarations and `rolldown-plugin-dts` bundling the `emulate` API types. `@emulators/*` packages now ship one `.d.ts` file per module instead of a single bundled file; the `types` entry points and exported types are unchanged (#346)
- Kept **declarations current in watch mode** so `dev` builds re-emit types when type-only source files change (#352)

Comment thread .oxlintrc.json Outdated
"typescript"
],
"categories": {
"correctness": "off"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 oxlint config disables the correctness rule category.

🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, .oxlintrc.json:7-8):

Problem: oxlint config disables the correctness rule category
Detail: The old eslint config enabled `tseslint.configs.recommended`, and oxlint enables its `correctness` category by default; the replacement config sets `"categories": { "correctness": "off" }` and turns on only an explicit ~20-rule allowlist of style/type-hygiene rules. That silently drops the bug-catch rules the old gate had (no-cond-assign, no-constant-condition, no-unreachable, no-self-compare, and oxlint's TS correctness rules). Unlike pnpm-workspace.yaml, which comments its tradeoffs, this file gives no rationale, so it reads as an accidental lint-gate weakening rather than a documented one.
Suggested fix: Either remove the `"correctness": "off"` override to restore oxlint's default-on correctness rules (roughly matching the old eslint recommended baseline), or keep it and document why (e.g. pending lint/TS7 compatibility) and list which correctness rules are intentionally re-enabled.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

The old eslint config enabled tseslint.configs.recommended, and oxlint enables its correctness category by default; the replacement config sets "categories": { "correctness": "off" } and turns on only an explicit ~20-rule allowlist of style/type-hygiene rules. That silently drops the bug-catch rules the old gate had (no-cond-assign, no-constant-condition, no-unreachable, no-self-compare, and oxlint's TS correctness rules). Unlike pnpm-workspace.yaml, which comments its tradeoffs, this file gives no rationale, so it reads as an accidental lint-gate weakening rather than a documented one.

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": [
    "typescript"
  ],
  "categories": {
    "correctness": "off"
  },

if (store.getData<boolean>("github.strict_scopes") !== true || c.get("authApp")) return next();
if (tokenMap?.has(presented)) return next();

if (/^Basic\s/i.test(header)) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Basic auth inconsistent on token endpoint.

Suggested change
if (/^Basic\s/i.test(header)) {
In the token-exchange handler, fall back to the Basic Authorization header when body client_id/client_secret are absent (parse it like `authenticateOAuthApp` does), so correct Basic credentials succeed and wrong ones get the endpoint's own incorrect_client_credentials response; or scope the strict middleware to skip the OAuth token endpoint.
🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, packages/@emulators/github/src/index.ts:687-688):

Problem: Basic auth inconsistent on token endpoint
Detail: The new global strict-mode middleware validates Basic OAuth-app credentials and 401s on a wrong secret (strict_scopes is default-true in the github-emulator package), but the POST /login/oauth/access_token handler only reads client_id/client_secret from the request body (`const bodyClientId = String(raw.client_id ?? "")`, routes/oauth.ts:196) and never from the Authorization header. Net effect for GitHub's documented `curl -u client_id:client_secret` pattern: a wrong Basic secret now gets 401 Bad credentials from the middleware, while a correct Basic secret passes the middleware and still gets a 200 incorrect_client_credentials from the handler — an inconsistent contract created by this middleware, and Basic-auth clients still cannot exchange codes at all.
Suggested fix: In the token-exchange handler, fall back to the Basic Authorization header when body client_id/client_secret are absent (parse it like `authenticateOAuthApp` does), so correct Basic credentials succeed and wrong ones get the endpoint's own incorrect_client_credentials response; or scope the strict middleware to skip the OAuth token endpoint.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

The new global strict-mode middleware validates Basic OAuth-app credentials and 401s on a wrong secret (strict_scopes is default-true in the github-emulator package), but the POST /login/oauth/access_token handler only reads client_id/client_secret from the request body (const bodyClientId = String(raw.client_id ?? ""), routes/oauth.ts:196) and never from the Authorization header. Net effect for GitHub's documented curl -u client_id:client_secret pattern: a wrong Basic secret now gets 401 Bad credentials from the middleware, while a correct Basic secret passes the middleware and still gets a 200 incorrect_client_credentials from the handler — an inconsistent contract created by this middleware, and Basic-auth clients still cannot exchange codes at all.

      if (/^Basic\\s/i.test(header)) {
        if (!isOAuthAppCredential(gh, header)) return badCredentials(c);
        // OAuth app credentials belong to the app, not to a user: drop the fallback identity.
        c.set("authUser", undefined);

return c.json({ message: "Bad credentials", documentation_url: docsUrl }, 401);
}

function isOAuthAppCredential(gh: GitHubStore, header: string): boolean {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Basic OAuth-app secret check duplicated in two modules.

🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, packages/@emulators/github/src/index.ts:738-744):

Problem: Basic OAuth-app secret check duplicated in two modules
Detail: The PR adds two near-identical security-critical validators that decode the Basic Authorization header and compare the client_secret against the stored OAuth app: `isOAuthAppCredential()` in src/index.ts:738 and `authenticateOAuthApp()` in src/routes/oauth.ts:~502. A future fix (trimming, encoding, scheme handling, clientId matching) applied to only one silently diverges the other's validation. The PR already created src/tokens.ts as the shared home for exactly this kind of cross-file auth logic (it moved `getTokenToClientId` there).
Suggested fix: Extract one helper into packages/@emulators/github/src/tokens.ts, e.g. `verifyOAuthAppBasicAuth(gh, header, clientId?)` returning the matched app or undefined, and have both the strict-mode middleware in index.ts and the DELETE /applications/:client_id/{token,grant} handlers in routes/oauth.ts call it.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

The PR adds two near-identical security-critical validators that decode the Basic Authorization header and compare the client_secret against the stored OAuth app: isOAuthAppCredential() in src/index.ts:738 and authenticateOAuthApp() in src/routes/oauth.ts:~502. A future fix (trimming, encoding, scheme handling, clientId matching) applied to only one silently diverges the other's validation. The PR already created src/tokens.ts as the shared home for exactly this kind of cross-file auth logic (it moved getTokenToClientId there).

function isOAuthAppCredential(gh: GitHubStore, header: string): boolean {
  const decoded = Buffer.from(header.replace(/^Basic\\s+/i, ""), "base64").toString();
  const separator = decoded.indexOf(":");
  if (separator < 0) return false;
  const oauthApp = gh.oauthApps.findOneBy("client_id", decoded.slice(0, separator));
  return !!oauthApp && constantTimeSecretEqual(decoded.slice(separator + 1), oauthApp.client_secret);
}

@aictrl-dev

aictrl-dev Bot commented Nov 16, 2026

Copy link
Copy Markdown

Code review

Verdict: Address the major findings before merging. · 🔴 0 · 🟠 2 · 🟡 4 · ⚪ 0 · 0/6 resolved

  • 🟡 .oxlintrc.json:7-8 — oxlint config disables the correctness rule category
  • 🟠 CHANGELOG.md:7-15 — Changelog omits 0.13.1 auth behavior changes
  • 🟡 packages/@emulators/github/src/index.ts:687-688 — Basic auth inconsistent on token endpoint
  • 🟡 packages/@emulators/github/src/index.ts:738-744 — Basic OAuth-app secret check duplicated in two modules
  • 🟡 packages/@emulators/github/src/routes/oauth.ts:180 — Token exchange debug-logs raw body with secret and code
  • 🟠 packages/github-emulator/src/index.ts:124-128 — assertPortFree added but never called before serve()
🤖 Fix all 6 open findings with your agent
Fix the following code review findings on aictrl-dev/github-emulator PR #11 (head branch).
Run the relevant tests/linters after each change.

1. .oxlintrc.json:7-8 — oxlint config disables the correctness rule category
   Detail: The old eslint config enabled `tseslint.configs.recommended`, and oxlint enables its `correctness` category by default; the replacement config sets `"categories": { "correctness": "off" }` and turns on only an explicit ~20-rule allowlist of style/type-hygiene rules. That silently drops the bug-catch rules the old gate had (no-cond-assign, no-constant-condition, no-unreachable, no-self-compare, and oxlint's TS correctness rules). Unlike pnpm-workspace.yaml, which comments its tradeoffs, this file gives no rationale, so it reads as an accidental lint-gate weakening rather than a documented one.
   Suggested fix: Either remove the `"correctness": "off"` override to restore oxlint's default-on correctness rules (roughly matching the old eslint recommended baseline), or keep it and document why (e.g. pending lint/TS7 compatibility) and list which correctness rules are intentionally re-enabled.
2. CHANGELOG.md:7-15 — Changelog omits 0.13.1 auth behavior changes
   Detail: The 0.13.1 entry documents only the toolchain upgrade, but this PR also ships user-observable auth behavior changes with no entry anywhere: (1) `createGitHubEmulator` now defaults `strict_scopes` to true, so tokens the emulator never issued get 401 Bad credentials instead of silently acting as the fallback user — a breaking change for existing consumers of the published package; (2) new `DELETE /applications/:client_id/{token,grant}` revocation endpoints; (3) OAuth authorization codes are now bound to the client_id they were issued to; (4) private repositories now answer 404 (not 401/403) to callers who cannot see them (orgs.test.ts expectation changed 403→404). The `strict_scopes` seed option is also absent from the docs. Users upgrading 0.13.0→0.13.1 get silent behavior flips.
   Suggested fix: Add 0.13.1 entries for: strict GitHub-style token validation (default-on in the `github-emulator` package; `strict_scopes: false` in the seed opts out), OAuth code↔client binding, the new token/grant revocation endpoints, and private-repo 404 masking; document `strict_scopes` in the README seed-options section next to `GitHubSeedConfig`.
3. packages/@emulators/github/src/index.ts:687-688 — Basic auth inconsistent on token endpoint
   Detail: The new global strict-mode middleware validates Basic OAuth-app credentials and 401s on a wrong secret (strict_scopes is default-true in the github-emulator package), but the POST /login/oauth/access_token handler only reads client_id/client_secret from the request body (`const bodyClientId = String(raw.client_id ?? "")`, routes/oauth.ts:196) and never from the Authorization header. Net effect for GitHub's documented `curl -u client_id:client_secret` pattern: a wrong Basic secret now gets 401 Bad credentials from the middleware, while a correct Basic secret passes the middleware and still gets a 200 incorrect_client_credentials from the handler — an inconsistent contract created by this middleware, and Basic-auth clients still cannot exchange codes at all.
   Suggested fix: In the token-exchange handler, fall back to the Basic Authorization header when body client_id/client_secret are absent (parse it like `authenticateOAuthApp` does), so correct Basic credentials succeed and wrong ones get the endpoint's own incorrect_client_credentials response; or scope the strict middleware to skip the OAuth token endpoint.
4. packages/@emulators/github/src/index.ts:738-744 — Basic OAuth-app secret check duplicated in two modules
   Detail: The PR adds two near-identical security-critical validators that decode the Basic Authorization header and compare the client_secret against the stored OAuth app: `isOAuthAppCredential()` in src/index.ts:738 and `authenticateOAuthApp()` in src/routes/oauth.ts:~502. A future fix (trimming, encoding, scheme handling, clientId matching) applied to only one silently diverges the other's validation. The PR already created src/tokens.ts as the shared home for exactly this kind of cross-file auth logic (it moved `getTokenToClientId` there).
   Suggested fix: Extract one helper into packages/@emulators/github/src/tokens.ts, e.g. `verifyOAuthAppBasicAuth(gh, header, clientId?)` returning the matched app or undefined, and have both the strict-mode middleware in index.ts and the DELETE /applications/:client_id/{token,grant} handlers in routes/oauth.ts call it.
5. packages/@emulators/github/src/routes/oauth.ts:180 — Token exchange debug-logs raw body with secret and code
   Detail: The token-exchange handler this PR hardens logs the raw request body — which contains the client_secret and the just-issued authorization code — to the debug channel whenever debug is enabled (`[OAuth token] raw body: ${rawText.slice(0, 500)}`), directly on the path where the new code↔client binding and revocation logic sits. These lines are pre-existing, but credential disclosure via logs undermines the credential-handling guarantees this PR adds, and secrets-in-logs is on the review checklist for modified paths.
   Suggested fix: Drop the raw-body debug line (the parsed-keys line already carries non-secret structure), and mask any remaining credential values (client_secret, code, access_token) in this handler's debug output.
6. packages/github-emulator/src/index.ts:124-128 — assertPortFree added but never called before serve()
   Detail: This PR adds `assertPortFree` to @emulators/core (with JSDoc "Await it before serve" to fail fast when another process holds the port on the wildcard address), exports it, and tests it — but nothing in the repository ever calls it. `createGitHubEmulator` still calls `serve({ port, hostname, fetch })` directly (packages/github-emulator/src/index.ts:124), so the documented macOS silent-bind bug the helper was written to fix still occurs: the emulator binds 127.0.0.1:4200 "successfully" while another process owns the wildcard port, and traffic is routed to the wrong listener. The new API ships as tested-but-dead code.
   Suggested fix: In `createGitHubEmulator`, await `assertPortFree(hostname, options.port ?? 4200)` immediately before the `serve(...)` call (or probe inside `serve()` itself), so the EADDRINUSE promise of the JSDoc is actually fulfilled for the shipped emulator.
📋 Out-of-diff findings (6)
Sev Location Finding
🟡 .oxlintrc.json:7-8 oxlint config disables the correctness rule category
🟠 CHANGELOG.md:7-15 Changelog omits 0.13.1 auth behavior changes
🟡 packages/@emulators/github/src/index.ts:687-688 Basic auth inconsistent on token endpoint
🟡 packages/@emulators/github/src/index.ts:738-744 Basic OAuth-app secret check duplicated in two modules
🟡 packages/@emulators/github/src/routes/oauth.ts:180 Token exchange debug-logs raw body with secret and code
🟠 packages/github-emulator/src/index.ts:124-128 assertPortFree added but never called before serve()

Reviewed 32 files · 0 inline · view all 6 findings ↗ · AI-generated — verify findings before acting · AI guidance and feedback


aictrl · AI code review for fast-moving teams · aictrl.dev

… document strict tokens

- .oxlintrc.json no longer turns off oxlint's default correctness category,
  which the previous ESLint recommended baseline covered (0 errors).
- createGitHubEmulator awaits assertPortFree before serve, so a port held on
  the wildcard address fails with EADDRINUSE instead of splitting traffic.
- README documents the strict token default and the strict_scopes opt-out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Br5cbz3i7Y5PaRdx3DUfXx
@byapparov

Copy link
Copy Markdown
Member Author

Review response — PR 11

Three findings fixed in 9b8b3763; three are upstream vercel-labs/emulate code and are deferred to an upstream report so the fork does not drift.

Issues addressed (pushed to this PR)

  • oxlint config disables the correctness rule category — .oxlintrc.json: removed the correctness: off override; pnpm lint has 0 errors (commit 9b8b3763).
  • Changelog omits auth behavior changes — packages/github-emulator/README.md: documents the strict token default (401 Bad credentials), the strict_scopes: false opt-out and private-repository 404. CHANGELOG.md 0.13.1 is upstream's release entry and is left unchanged; this fork's package is private 0.1.0 (commit 9b8b3763).
  • assertPortFree added but never called before serve() — packages/github-emulator/src/index.ts: createGitHubEmulator awaits assertPortFree before serve (commit 9b8b3763).

Review claims verified false (no change needed)

None.

Not addressed here

Upstream code from vercel-labs/emulate 388, deferred to an upstream issue or PR rather than patched in the fork:

  • Basic auth inconsistent on token endpoint — aictrl exchanges codes with body credentials, which work.
  • Basic OAuth-app secret check duplicated in two modules — both copies are upstream's.
  • Token exchange debug-logs raw body — pre-existing upstream line; the debug channel is not enabled in aictrl's stack.

* bind. Await it before `serve`: macOS lets a specific address bind a port another process holds on the wildcard
* address. The other process sees one short connection.
*/
export async function assertPortFree(hostname: string | undefined, port: number): Promise<void> {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 assertPortFree probes only one resolved address.

Suggested change
export async function assertPortFree(hostname: string | undefined, port: number): Promise<void> {
Resolve with `lookup(host, { all: true })` and probe every returned address (or at minimum both 127.0.0.1 and ::1 for localhost-style names); throw EADDRINUSE if any of them accepts a connection.
🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, packages/@emulators/core/src/http.ts:453-462):

Problem: assertPortFree probes only one resolved address
Detail: assertPortFree resolves the hostname once and probes a single address. For 'localhost', dns.lookup often returns ::1 first while another process holds the port on 127.0.0.1: the probe to [::1] fails, the function resolves, serve() binds the IPv6 address, and traffic sent to 127.0.0.1:port silently reaches the foreign listener — exactly the split-listener condition the helper was added to prevent. Same gap for hostnames with multiple A records. Only affects callers passing a DNS hostname (createGitHubEmulator defaults to the literal 127.0.0.1, which skips lookup).
Suggested fix: Resolve with `lookup(host, { all: true })` and probe every returned address (or at minimum both 127.0.0.1 and ::1 for localhost-style names); throw EADDRINUSE if any of them accepts a connection.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

assertPortFree resolves the hostname once and probes a single address. For 'localhost', dns.lookup often returns ::1 first while another process holds the port on 127.0.0.1: the probe to [::1] fails, the function resolves, serve() binds the IPv6 address, and traffic sent to 127.0.0.1:port silently reaches the foreign listener — exactly the split-listener condition the helper was added to prevent. Same gap for hostnames with multiple A records. Only affects callers passing a DNS hostname (createGitHubEmulator defaults to the literal 127.0.0.1, which skips lookup).

export async function assertPortFree(hostname: string | undefined, port: number): Promise<void> {
  const host = hostname ?? "127.0.0.1";
  if (port === 0 || host === "0.0.0.0" || host === "::") return;
  const address = isIP(host)
    ? host
    : await lookup(host).then(
        (r) => r.address,
        () => undefined,
      );
  if (!address) return;
  const taken = await new Promise<boolean>((resolve) => {
    try {
      const socket = connect({ host: address, port, timeout: 300 });

if (store.getData<boolean>("github.strict_scopes") !== true || c.get("authApp")) return next();
if (tokenMap?.has(presented)) return next();

if (/^Basic\s/i.test(header)) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Permissive mode maps Basic headers to fallback user.

Suggested change
if (/^Basic\s/i.test(header)) {
Detect `/^Basic\s/i` headers before the strict_scopes check and handle them uniformly in both modes: validate via isOAuthAppCredential and drop the fallback identity (or reject), so a Basic header never resolves to the default user regardless of mode.
🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, packages/@emulators/github/src/index.ts:687-694):

Problem: Permissive mode maps Basic headers to fallback user
Detail: The new middleware validates `Authorization: Basic` headers against OAuth app credentials only when strict_scopes is true; in permissive mode the Basic branch is skipped entirely. Core authMiddleware (middleware/auth.ts:85,108-118) does not recognize the Basic scheme, treats the whole 'Basic <b64>' string as a token, and — when a fallback user is configured — assigns it the fallback identity. So `Authorization: Basic AAAA` authenticates as the default user in permissive mode but gets 401 in strict mode, an inconsistency the PR's own credential-fidelity work leaves in place. Permissive mode remains the default for direct @emulators/github consumers (only the github-emulator wrapper flips strict_scopes to true).
Suggested fix: Detect `/^Basic\s/i` headers before the strict_scopes check and handle them uniformly in both modes: validate via isOAuthAppCredential and drop the fallback identity (or reject), so a Basic header never resolves to the default user regardless of mode.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

The new middleware validates Authorization: Basic headers against OAuth app credentials only when strict_scopes is true; in permissive mode the Basic branch is skipped entirely. Core authMiddleware (middleware/auth.ts:85,108-118) does not recognize the Basic scheme, treats the whole 'Basic ' string as a token, and — when a fallback user is configured — assigns it the fallback identity. So Authorization: Basic AAAA authenticates as the default user in permissive mode but gets 401 in strict mode, an inconsistency the PR's own credential-fidelity work leaves in place. Permissive mode remains the default for direct @emulators/github consumers (only the github-emulator wrapper flips strict_scopes to true).

      if (store.getData<boolean>("github.strict_scopes") !== true || c.get("authApp")) return next();
      if (tokenMap?.has(presented)) return next();

      if (/^Basic\s/i.test(header)) {
        if (!isOAuthAppCredential(gh, header)) return badCredentials(c);
        // OAuth app credentials belong to the app, not to a user: drop the fallback identity.
        c.set("authUser", undefined);
        c.set("authToken", undefined);
        c.set("authScopes", undefined);
        return next();
      }

      return badCredentials(c);
    });

tokenMap?.delete(token);
getTokenToClientId(store).delete(token);
getRevokedTokens(store).add(token);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ Revoked-token registry grows without bound.

Suggested change
}
Cap the set (keep most recent N entries) or drop entries older than a TTL when the set is materialized, mirroring the pendingCodes TTL pattern already used in oauth.ts.
🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, packages/@emulators/github/src/tokens.ts:35-36):

Problem: Revoked-token registry grows without bound
Detail: getRevokedTokens only ever adds entries; nothing prunes, caps or expires the set, and it is snapshotted/persisted with the store. In a long-lived or persisted emulator every revocation accumulates a token string forever even though freshly generated random tokens can never collide with retired entries.
Suggested fix: Cap the set (keep most recent N entries) or drop entries older than a TTL when the set is materialized, mirroring the pendingCodes TTL pattern already used in oauth.ts.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

getRevokedTokens only ever adds entries; nothing prunes, caps or expires the set, and it is snapshotted/persisted with the store. In a long-lived or persisted emulator every revocation accumulates a token string forever even though freshly generated random tokens can never collide with retired entries.

export function revokeOAuthToken(store: Store, tokenMap: TokenMap | undefined, token: string): void {
  tokenMap?.delete(token);
  getTokenToClientId(store).delete(token);
  getRevokedTokens(store).add(token);
}

"type-check": "tsc --noEmit",
"lint": "eslint src",
"type-check": "tsc-ts --noEmit",
"type-check:tsc": "tsc --noEmit",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ type-check:tsc script referenced nowhere.

Suggested change
"type-check:tsc": "tsc --noEmit",
If it is an intentional manual fallback, mention it next to `pnpm type-check` in the README; otherwise drop it from the root and the three package scripts.
🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, packages/github-emulator/package.json:37):

Problem: type-check:tsc script referenced nowhere
Detail: The new `type-check:tsc` script (added to the root and all three packages, mirroring `type-check` which now runs `tsc-ts --noEmit`) is not invoked by anything at head: CI (.github/workflows/ci.yml) runs only `pnpm type-check`, and no docs, examples or scripts call it. Unless it is a deliberate manual escape hatch for cross-checking the tsc-ts wrapper, it is a redundant near-duplicate script spread across four package.json files.
Suggested fix: If it is an intentional manual fallback, mention it next to `pnpm type-check` in the README; otherwise drop it from the root and the three package scripts.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

The new type-check:tsc script (added to the root and all three packages, mirroring type-check which now runs tsc-ts --noEmit) is not invoked by anything at head: CI (.github/workflows/ci.yml) runs only pnpm type-check, and no docs, examples or scripts call it. Unless it is a deliberate manual escape hatch for cross-checking the tsc-ts wrapper, it is a redundant near-duplicate script spread across four package.json files.

"devDependencies": {
"@emulators/core": "workspace:*",
"@emulators/github": "workspace:*",
"rolldown": "1.2.16",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ Exact version pins break repo's caret-range style.

🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, packages/github-emulator/package.json:47-49):

Problem: Exact version pins break repo's caret-range style
Detail: The new build tooling deps are pinned exactly (`rolldown: 1.2.16`, `rolldown-plugin-dts: 0.29.0`, and `tsc-ts: 0.1.3`, the last also in @emulators/core and @emulators/github) while every other dependency across the workspace uses `^` ranges. The exact pins also sit oddly beside `minimumReleaseAgeExclude: [\"tsc-ts\", \"@tsc-ts/*\"]` in pnpm-workspace.yaml, whose stated purpose is to allow freshly released versions — which an exact pin forecloses.
Suggested fix: Either switch to caret ranges consistent with the rest of the workspace, or add a brief comment noting these three are intentionally pinned (e.g. for reproducible dts bundling under TypeScript 7) so the divergence is documented.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

The new build tooling deps are pinned exactly (rolldown: 1.2.16, rolldown-plugin-dts: 0.29.0, and tsc-ts: 0.1.3, the last also in @emulators/core and @emulators/github) while every other dependency across the workspace uses ^ ranges. The exact pins also sit oddly beside minimumReleaseAgeExclude: [\"tsc-ts\", \"@tsc-ts/*\"] in pnpm-workspace.yaml, whose stated purpose is to allow freshly released versions — which an exact pin forecloses.

@@ -33,8 +33,9 @@
"scripts": {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ .types declaration dir is never cleaned.

🤖 Fix with your agent
Fix this code review finding (aictrl-dev/github-emulator PR #11, packages/github-emulator/package.json:33-39):

Problem: .types declaration dir is never cleaned
Detail: Unlike @emulators/core and @emulators/github (`clean: rm -rf dist .turbo`), the github-emulator package has no clean script and `build: tsup --clean` only wipes dist. The `.types` intermediate dir written by tsconfig.build.json (and read by scripts/bundle-dts.mjs) survives rebuilds, so declarations from deleted or renamed sources can accumulate and be picked up by later declaration bundling runs.
Suggested fix: Add `"clean": "rm -rf dist .types .turbo"` matching the sibling packages, and/or have the type emission start by removing .types.

Implement the fix on the PR head branch and add a regression test that fails before the fix and passes after.
Why this matters

Unlike @emulators/core and @emulators/github (clean: rm -rf dist .turbo), the github-emulator package has no clean script and build: tsup --clean only wipes dist. The .types intermediate dir written by tsconfig.build.json (and read by scripts/bundle-dts.mjs) survives rebuilds, so declarations from deleted or renamed sources can accumulate and be picked up by later declaration bundling runs.

@aictrl-dev

aictrl-dev Bot commented Nov 16, 2026

Copy link
Copy Markdown

Code review

Verdict: Looks good — only minor / nit comments below. · 🔴 0 · 🟠 0 · 🟡 6 · ⚪ 4 · 0/10 resolved

  • 🟡 packages/@emulators/core/src/http.ts:453-462 — assertPortFree probes only one resolved address
  • 🟡 packages/@emulators/github/README.md:160-185 — strict_scopes missing from @emulators/github README
  • 🟡 packages/@emulators/github/src/index.ts:687-694 — Permissive mode maps Basic headers to fallback user
  • 🟡 packages/@emulators/github/src/routes/oauth.ts:163 — Debug log prints full OAuth authorization code
  • 🟡 packages/@emulators/github/src/routes/repos.ts:526-527 — PUT /topics 401/403s invisible private repos (oracle)
  • ⚪ packages/@emulators/github/src/tokens.ts:35-36 — Revoked-token registry grows without bound
  • ⚪ packages/github-emulator/package.json:33-39 — .types declaration dir is never cleaned
  • ⚪ packages/github-emulator/package.json:37 — type-check:tsc script referenced nowhere
  • ⚪ packages/github-emulator/package.json:47-49 — Exact version pins break repo's caret-range style
  • 🟡 README.md:83 — Root README omits strict-token default of emulator
🤖 Fix all 10 open findings with your agent
Fix the following code review findings on aictrl-dev/github-emulator PR #11 (head branch).
Run the relevant tests/linters after each change.

1. packages/@emulators/core/src/http.ts:453-462 — assertPortFree probes only one resolved address
   Detail: assertPortFree resolves the hostname once and probes a single address. For 'localhost', dns.lookup often returns ::1 first while another process holds the port on 127.0.0.1: the probe to [::1] fails, the function resolves, serve() binds the IPv6 address, and traffic sent to 127.0.0.1:port silently reaches the foreign listener — exactly the split-listener condition the helper was added to prevent. Same gap for hostnames with multiple A records. Only affects callers passing a DNS hostname (createGitHubEmulator defaults to the literal 127.0.0.1, which skips lookup).
   Suggested fix: Resolve with `lookup(host, { all: true })` and probe every returned address (or at minimum both 127.0.0.1 and ::1 for localhost-style names); throw EADDRINUSE if any of them accepts a connection.
2. packages/@emulators/github/README.md:160-185 — strict_scopes missing from @emulators/github README
   Detail: This PR adds `strict_scopes?: boolean` to the exported GitHubSeedConfig and persists it in seedFromConfig (src/index.ts:48, 294-296), but the Seed Configuration section of the package that defines the type documents every sibling key (users, orgs, repos, oauth_apps, apps) without mentioning `strict_scopes`, and the Auth section doesn't note that revoked tokens always 401 and private repos now 404. Only packages/github-emulator/README.md documents the option, so direct consumers of `@emulators/github` / `seedFromConfig` discover it only from the type definition.
   Suggested fix: Add a `strict_scopes` entry to the Seed Configuration section (noting the default is false in this package; the github-emulator wrapper defaults it to true), plus a line in the Auth section that revoked tokens are always rejected and private repos return 404 to callers without access.
3. packages/@emulators/github/src/index.ts:687-694 — Permissive mode maps Basic headers to fallback user
   Detail: The new middleware validates `Authorization: Basic` headers against OAuth app credentials only when strict_scopes is true; in permissive mode the Basic branch is skipped entirely. Core authMiddleware (middleware/auth.ts:85,108-118) does not recognize the Basic scheme, treats the whole 'Basic <b64>' string as a token, and — when a fallback user is configured — assigns it the fallback identity. So `Authorization: Basic AAAA` authenticates as the default user in permissive mode but gets 401 in strict mode, an inconsistency the PR's own credential-fidelity work leaves in place. Permissive mode remains the default for direct @emulators/github consumers (only the github-emulator wrapper flips strict_scopes to true).
   Suggested fix: Detect `/^Basic\s/i` headers before the strict_scopes check and handle them uniformly in both modes: validate via isOAuthAppCredential and drop the fallback identity (or reject), so a Basic header never resolves to the default user regardless of mode.
4. packages/@emulators/github/src/routes/oauth.ts:163 — Debug log prints full OAuth authorization code
   Detail: The OAuth callback's redirect debug line logs the first 120 characters of the redirect target, which embeds the complete single-use authorization code (`code=` + 40 hex chars — the code parameter appears before state, so the slice captures it in full). Anyone reading debug output within the code's TTL window can exchange it for an access token, undermining the credential handling this PR adds on the adjacent token-exchange path. Companion to the already-recorded raw-body log at line 181; this is a separate leak on a separate line.
   Suggested fix: Redact the code parameter before logging, e.g. `target.replace(/code=[^&]+/, "code=***")`.
5. packages/@emulators/github/src/routes/repos.ts:526-527 — PUT /topics 401/403s invisible private repos (oracle)
   Detail: The PR masks private-repo existence by converting 401/403 to 404 in assertRepoRead/Write/Permission/Admin/ContentsWrite, and GET /repos/:owner/:repo/topics follows suit (line 517 calls assertRepoRead) — but PUT /repos/:owner/:repo/topics (repos.ts:520-527) goes straight to assertAuthenticatedUser/hasRepoAdmin without assertRepoRead. An anonymous caller gets 401 and an authenticated non-collaborator gets 403 for an existing private repo they cannot see, while every other endpoint returns 404 for the same repo — a status-code oracle that defeats the masking this PR introduces.
   Suggested fix: Call assertRepoRead(gh, c.get("authUser"), repo) right after the lookupRepo 404 check in the PUT handler, mirroring the GET handler; consider auditing other write routes that skip assertRepoRead for the same oracle.
6. packages/@emulators/github/src/tokens.ts:35-36 — Revoked-token registry grows without bound
   Detail: getRevokedTokens only ever adds entries; nothing prunes, caps or expires the set, and it is snapshotted/persisted with the store. In a long-lived or persisted emulator every revocation accumulates a token string forever even though freshly generated random tokens can never collide with retired entries.
   Suggested fix: Cap the set (keep most recent N entries) or drop entries older than a TTL when the set is materialized, mirroring the pendingCodes TTL pattern already used in oauth.ts.
7. packages/github-emulator/package.json:33-39 — .types declaration dir is never cleaned
   Detail: Unlike @emulators/core and @emulators/github (`clean: rm -rf dist .turbo`), the github-emulator package has no clean script and `build: tsup --clean` only wipes dist. The `.types` intermediate dir written by tsconfig.build.json (and read by scripts/bundle-dts.mjs) survives rebuilds, so declarations from deleted or renamed sources can accumulate and be picked up by later declaration bundling runs.
   Suggested fix: Add `"clean": "rm -rf dist .types .turbo"` matching the sibling packages, and/or have the type emission start by removing .types.
8. packages/github-emulator/package.json:37 — type-check:tsc script referenced nowhere
   Detail: The new `type-check:tsc` script (added to the root and all three packages, mirroring `type-check` which now runs `tsc-ts --noEmit`) is not invoked by anything at head: CI (.github/workflows/ci.yml) runs only `pnpm type-check`, and no docs, examples or scripts call it. Unless it is a deliberate manual escape hatch for cross-checking the tsc-ts wrapper, it is a redundant near-duplicate script spread across four package.json files.
   Suggested fix: If it is an intentional manual fallback, mention it next to `pnpm type-check` in the README; otherwise drop it from the root and the three package scripts.
9. packages/github-emulator/package.json:47-49 — Exact version pins break repo's caret-range style
   Detail: The new build tooling deps are pinned exactly (`rolldown: 1.2.16`, `rolldown-plugin-dts: 0.29.0`, and `tsc-ts: 0.1.3`, the last also in @emulators/core and @emulators/github) while every other dependency across the workspace uses `^` ranges. The exact pins also sit oddly beside `minimumReleaseAgeExclude: [\"tsc-ts\", \"@tsc-ts/*\"]` in pnpm-workspace.yaml, whose stated purpose is to allow freshly released versions — which an exact pin forecloses.
   Suggested fix: Either switch to caret ranges consistent with the rest of the workspace, or add a brief comment noting these three are intentionally pinned (e.g. for reproducible dts bundling under TypeScript 7) so the divergence is documented.
10. README.md:83 — Root README omits strict-token default of emulator
   Detail: The root README's createGitHubEmulator section describes options, seeding and reset semantics but does not mention that this edition defaults to strict credential checking (unrecognized bearer tokens — e.g. tokens issued before reset() — get 401 Bad credentials) or that private repos answer 404 to callers who cannot see them. That is the headline behavioral difference from upstream for repo-level readers of this fork, and it is currently documented only in packages/github-emulator/README.md:21.
   Suggested fix: Add one sentence to the createGitHubEmulator paragraph: unknown bearer tokens get 401 Bad credentials by default (set `strict_scopes: false` in the seed to restore upstream's default-user fallback) and private repositories return 404 to callers who cannot see them.
📋 Out-of-diff findings (10)
Sev Location Finding
🟡 packages/@emulators/core/src/http.ts:453-462 assertPortFree probes only one resolved address
🟡 packages/@emulators/github/README.md:160-185 strict_scopes missing from @emulators/github README
🟡 packages/@emulators/github/src/index.ts:687-694 Permissive mode maps Basic headers to fallback user
🟡 packages/@emulators/github/src/routes/oauth.ts:163 Debug log prints full OAuth authorization code
🟡 packages/@emulators/github/src/routes/repos.ts:526-527 PUT /topics 401/403s invisible private repos (oracle)
⚪ packages/@emulators/github/src/tokens.ts:35-36 Revoked-token registry grows without bound
⚪ packages/github-emulator/package.json:33-39 .types declaration dir is never cleaned
⚪ packages/github-emulator/package.json:37 type-check:tsc script referenced nowhere
⚪ packages/github-emulator/package.json:47-49 Exact version pins break repo's caret-range style
🟡 README.md:83 Root README omits strict-token default of emulator

Reviewed 33 files · 0 inline · view all 10 findings ↗ · AI-generated — verify findings before acting · AI guidance and feedback


aictrl · AI code review for fast-moving teams · aictrl.dev

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants